home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_436 / keymacro / keymacro.doc < prev    next >
Text File  |  1992-05-06  |  13KB  |  287 lines
  1. ======================================================================
  2. =========================== KeyMacro v1.8 ============================
  3. ================== * A macro key handler utility * ===================
  4. ======================================================================
  5.  
  6. ============================= IMPORTANT ==============================
  7. ======================================================================
  8. The  current release of KeyMacro requires arp.library and Null-Handler
  9. to  be  present  in  your system.  Put the library into LIBS:  and the
  10. handlers into L:.  Then add the following lines to DEVS:MountList:
  11.  
  12.     NULL:    Handler        = L:Null-Handler
  13.         Stacksize    = 500
  14.         Priority    = 5
  15.         GlobVec        = -1
  16.     #
  17.  
  18. You  _M_U_S_T_  install  the Null-Handler using the CLI command 'Mount
  19. NULL:' before starting KeyMacro or the KeyMacro handler won't budge.
  20.  
  21. ============================ BACKGROUND ==============================
  22. ======================================================================
  23. Some  time  ago  I  played around with a keymap editor to customize my
  24. keymap  settings.  But there was a feature I missed:  there wasn't any
  25. hot-key  support  (just  like  PopCLI  or  DMouse).  I also discovered
  26. another  disadvantage:   to change the keymap settings you had to load
  27. the  keymap  editor, edit the map, save it to disk and then install it
  28. via  SetMap  -  and even that didn't guarantee that the new keymap was
  29. accepted:   do  you  remember that SetMap does not load new keymaps if
  30. the  name matches a keymap already in memory?  Furthermore keymap keys
  31. may only generate string sequences of up to 32 characters.  With these
  32. topics in mind I decided to write my own keyboard macro handler.
  33.  
  34. ============================= FEATURES ===============================
  35. ======================================================================
  36. KeyMacro  provides  an  easy  way to manage keyboard macros (character
  37. sequences)  and  hot-key program execution.  You edit a script file in
  38. which  all  required key combinations are defined and call KeyMacro to
  39. update the macro list - that's all.  You can map up to eight functions
  40. to  each  key, including keys such as the cursor keys, the return key,
  41. etc.   The hot-key programs will use an AmigaDOS search path list when
  42. getting  executed.  Each macro key call gets processed asynchronously,
  43. i.e.   invoking  one  hot-key  command  after the other will start all
  44. commands in a row, nothing will be skipped.
  45.  
  46. =========================== INSTALLATION =============================
  47. ======================================================================
  48. Place  KeyMacro-Handler in L:, KeyMacro in C:  or SYS:, arp.library in
  49. LIBS:,   copy   your   KeyMacro.config  to  S:.   Type  "KeyMacro"  to
  50. install/update  macro  keys, "KeyMacro quit" to remove.  Note:  if the
  51. installation  fails  the  main  process  ("KeyMacro")  will wait for a
  52. handshake signal which may never arrive.  In this case pressing CTRL-C
  53. will  stop  the  main  process.   It will shut down and issue an error
  54. message.
  55.  
  56. =============================== USAGE ================================
  57. ======================================================================
  58. KeyMacro is controlled via a script file.  Here is a sample:
  59.  
  60.     ; KeyMacro v1.8 configuration file.
  61.     ; The semicolon says that this is a comment:
  62.  
  63.     ; Some keyboard macros.
  64.  
  65.     key ctrl+esc = "EndCLI > NIL:\n"
  66.     key lalt+0 = "CD DF0:\n"
  67.     key lalt+1 = "CD DF1:\n"
  68.  
  69.     ; A hot-key command definition
  70.  
  71.     command lalt+v = "C:vt100 +i s:vt100.init" window "VT100"
  72.  
  73. Each  definition  must  be  "key"  or "command".  "Key" means that the
  74. following  definition  will be a sequence of characters to be inserted
  75. into  the input stream.  "Command" means that the following definition
  76. will be the name and the arguments of a program to be executed.
  77.     The  macro  type  is  followed  by  the  key combination to be
  78. pressed to execute the macro definition.  This combination consists of
  79. the keyboard qualifier and the key.  An unlimited number of qualifiers
  80. is allowed.  KeyMacro knows the following qualifiers:
  81.  
  82.     NONE ..........    No qualifier (note: a qualifier MUST be given!)    
  83.     CTRL ..........    The control key
  84.     NUMPAD ........    The numeric pad
  85.     LSHIFT ........    The left shift key
  86.     RSHIFT ........    The right shift key
  87.     LALT ..........    The left alternate key
  88.     RALT ..........    The right alternate key
  89.     LAMIGA ........    The left Amiga key (Commodore key)
  90.     RAMIGA ........    The right Amiga key
  91.  
  92. A qualifier must be given or the macro parser will panic; if you don't
  93. need a qualifier simply enter NONE as the qualifier.
  94.     The  qualifier  is  followed  by  the  key to attach the macro
  95. expression  to.   This  can  be  any  key  on  the keyboard, including
  96. function keys, cursor keys, etc.  If there is no ASCII value available
  97. for the key, you can take a name from the following list:
  98.  
  99.     TAB ...........    The tabulator key
  100.     ESC ...........    The escape key
  101.     SPACE .........    The space key
  102.     RETURN ........    The return key
  103.     ENTER .........    The enter key (numeric pad)
  104.     DEL ...........    The delete key
  105.     BACKSPACE .....    The backspace key
  106.     HELP ..........    The help key
  107.  
  108.     LEFT ..........    The cursor-left key
  109.     RIGHT .........    The cursor-right key
  110.     UP ............    The cursor-up key
  111.     DOWN ..........    The cursor-down key
  112.  
  113.     F1 ............    The function key #1
  114.     F2 ............    The function key #2
  115.     F3 ............    The function key #3
  116.     F4 ............    The function key #4
  117.     F5 ............    The function key #5
  118.     F6 ............    The function key #6
  119.     F7 ............    The function key #7
  120.     F8 ............    The function key #8
  121.     F9 ............    The function key #9
  122.     F10 ...........    The function key #10
  123.  
  124. These  equivalents  can  be  used just like characters.  Note:  if you
  125. enter more than one single character as the command key only the first
  126. character will be taken (except for the key names listed above).
  127.     The key is followed by a '=' sign, this tells the macro parser
  128. to   remember   the  following  string  as  the  macro  string  to  be
  129. entered/executed.   This  string  must  be  enclosed  in quotes or the
  130. parser will take only the first word.  Inside this string sequences of
  131. two  characters can be used to generate key codes not supported by the
  132. ASCII keyboard.  These sequences are:
  133.  
  134.     \u ............    Cursor-up key
  135.     \d ............    Cursor-down key
  136.     \l ............    Cursor-left key
  137.     \r ............    Cursor-right key
  138.  
  139.     \n ............    The return key
  140.  
  141.     \h ............    The help key
  142.     \b ............    The backspace key
  143.     \e ............    The delete key (sorry, \d was already used)
  144.     \f1 - \f10 ....    The function keys
  145.     \" ............    A quote
  146.     \\ ............    The escape symbol ('\')
  147.  
  148. A  hot-key  command  definition can be followed by a "window" keyword.
  149. This  keyword  identifies  the next string (enclosed in quotes) as the
  150. typical window title of the command to be loaded.  Before this command
  151. is  executed  each open window is checked for this title.  If a window
  152. title matches the name it is brought to the front, no new command will
  153. be loaded.
  154.     KeyMacro  has  some  problems if you try to map macros to keys
  155. which are to be found on the standard keyboard and the numeric key pad
  156. as  well.   The  keymap  routine will map the macro to the numeric key
  157. pad.   The  only  exception  are  the number keys which are by default
  158. mapped to the number row.
  159.  
  160.                                   *
  161.  
  162.            KeyMacro has the following command-line options:
  163.  
  164. Startup .......    Followed  by  the  name  of  the file to be used as
  165.         configuration  file will keep KeyMacro from looking
  166.         for S:KeyMacro.config as the standard configuration
  167.         file.
  168.  
  169. Quit ..........    Removes KeyMacro from memory.
  170.  
  171. Delay .........    You  will  need  this  keyword  if  the  keypresses
  172.         KeyMacro  emits  do  not  produce sensible results,
  173.         i.e.   the  output  is  garbled  or  characters are
  174.         swallowed.   You  may specify the delay between the
  175.         single  keypresses.   The  rate  must  be  given in
  176.         microseconds, i.e.  a value of 1000000 will produce
  177.         a  delay  of  one second (you won't be needing this
  178.         much,  will  you?), 500000 will wait half a second.
  179.         For  technical  reasons the delay rate has to be >=
  180.         10000.
  181.  
  182. Info ..........    Gives a brief information on the program.
  183.  
  184. =============================== FUTURE ===============================
  185. ======================================================================
  186. There  is  a  good  chance  that  there  will  be  no further KeyMacro
  187. revisions  available  for  machines  running Kickstart revisions lower
  188. than  2.x.   I plan to bring KeyMacro to an entirely system-integrated
  189. state  in  which  there is no need to rely on undocumented system data
  190. structures  (keymap  inversion) and to get along with DOS the way I am
  191. currently  dealing  with it.  KeyMacro users:  what is your opinion on
  192. this topic?
  193.  
  194. ============================== CREDITS ===============================
  195. ======================================================================
  196. Credits  go  to ARP Programmers for the most recent version of ARP, to
  197. Paul  Kienitz  for  his  FakeCLI  package, to Mark R.  Rinfret for the
  198. buffered Arp I/O routines and to Matt Dillon for DMouse.
  199.     A special mention must also go to Bill Hawes, author of ARexx,
  200. and  to the authors of CygnusEd Pro 2 (Bruce Dawson & Colin Fox) whose
  201. programs both controlled the compiler runs.
  202.  
  203. ================== COPY FEE, AUTHORS REQUEST, ETC. ===================
  204. ======================================================================
  205. This  is the first time I release a program as shareware.  Consider it
  206. as  a  "test balloon" for coming projects.  A small contribution of at
  207. least $10 US or at least DM 15,- will insure your registration, giving
  208. you  the  opportunity  to  receive  updates, new programs from MXM and
  209. more.   Think about it, if you like this program and use it often this
  210. small  amount  of  money  will support the author and encourage him to
  211. start new projects.
  212.  
  213.        Send comments, bug reports, ideas and contributions to:
  214.  
  215.                           Olaf Barthel, MXM
  216.                           Brabeckstrasse 35
  217.                           D-3000 Hannover 71
  218.  
  219.                      Federal Republic of Germany
  220.  
  221. Permission  hereby  granted  to  re-distribute  KeyMacro  v1.8  in its
  222. entirety for non profit usage only.
  223.  
  224. ============ REVISION HISTORY (most recent change first) =============
  225. ======================================================================
  226. V1.8    The  keymap  inversion  routines  were  responsible  for funny
  227.     sideeffects,  such  as  characters  being swallowed instead of
  228.     being fed into the input stream.  It took me about three hours
  229.     to figure out what a `dead key-modifiable' keymap entry is and
  230.     another hour to program my own keymap reader.
  231.  
  232. V1.7    Added  the  delay  keyword  and  fixed a bug in KeyMacro which
  233.     caused a crash if KeyMacro-Handler could not be loaded.
  234.  
  235. V1.6    Thanks  to  user  persistance  KeyMacro was thoroughly revised
  236.     (yes, I mean what I say!).  Bert L.  Allen discovered problems
  237.     with the numeric key pad, Ralf Thanner suggested that I should
  238.     get rid of mxm.library, Martin Berndt and Benito Lombardi made
  239.     helpful  suggestions.   The  dreaded  mxm.library  was finally
  240.     removed,  saving about 20 KByte when there is no other program
  241.     to  access  the mxm.library routines.  The routine to simulate
  242.     the  key  events  will produce a key-down followed by a key-up
  243.     event.   Macros will no longer invoke other macros on the way.
  244.     InputEvents  created  by  KeyMacro-Handler  will  have a valid
  245.     timestamp.   Key  names are no longer abbreviated (i.e.  'f10'
  246.     !=  'f1').  The return key will finally work in cases where it
  247.     wouldn't work in revision 1.4.
  248.  
  249. V1.5    Small changes to library and code, recompiled  using  the  new
  250.     Aztec 'C' 5.0b compiler.
  251.  
  252. V1.4    Wow!   It  works!   The reasons for the constant failures were
  253.     located  in  1) mxm.library, 2) in the Arp wrapper for Lattice
  254.     'C',   3)   in   KeyMacro   itself   and   4)   of  course  in
  255.     KeyMacro-Handler.   Needless to say, mxm.library was fixed and
  256.     the code has once more changed the compiler - KeyMacro 1.4 now
  257.     compiles   under   Aztec   5.0.    Programs   started  by  the
  258.     executor-process will no longer block until the program exits.
  259.     This  is  now  probably  the only input.device example program
  260.     written  in  Aztec  'C'  which doesn't use ANY inline assembly
  261.     language code (#asm/#endasm).
  262.  
  263. V1.3    Well, I wouldn't shoot  my  grandma  to get it working, but it
  264.     really  starts  to  become  a  nuisance:  1.2 still wasn't the
  265.     success  I  had  expected.  I took a second look into RKM Exec
  266.     and  discovered  that  interrupt handlers be located in public
  267.     ram.   As  a  result  almost all static data declarations have
  268.     been replaced by memory allocations.
  269.  
  270. V1.2    I  guess  you know what happened:  it still didn't work right.
  271.     The  code  is  now  much  more compact and has been recompiled
  272.     using Lattice 'C' 5.04.
  273.  
  274. V1.1    KeyMacro  obviously  worked  on  only  one machine:  my Amiga.
  275.     This  is the first attempt to fix it.  I cleaned up the code I
  276.     didn't  think  to  be that much important which hopefully will
  277.     fix the problem.
  278.  
  279. V1.0    First  public  release;  seems  that  it  works (what did I do
  280.     wrong?).
  281.  
  282.                                   *
  283.  
  284.              Do only its possibilities make it an Amiga?
  285.  
  286.                         WHERE IS THE MAGIC ???
  287.